Document new clipboard apis

These are surface-based replacements for some pixbuf apis.

diff --git a/docs/reference/gtk/gtk4-sections.txt b/docs/reference/gtk/gtk4-sections.txt
index 38591fc66fab2850b5ff2a7485011954e1f1894f..8edf9fb1da3439950ad194fef5c7406ebefb9302 100644 (file)
--- a/docs/reference/gtk/gtk4-sections.txt
+++ b/docs/reference/gtk/gtk4-sections.txt
@@ -5302,6 +5302,7 @@ gtk_clipboard_get_owner
 gtk_clipboard_clear
 gtk_clipboard_set_text
 gtk_clipboard_set_image
+gtk_clipboard_set_surface
 gtk_clipboard_request_contents
 gtk_clipboard_request_text
 gtk_clipboard_request_image
@@ -5311,6 +5312,7 @@ gtk_clipboard_request_uris
 gtk_clipboard_wait_for_contents
 gtk_clipboard_wait_for_text
 gtk_clipboard_wait_for_image
+gtk_clipboard_wait_for_surface
 gtk_clipboard_wait_for_rich_text
 gtk_clipboard_wait_for_uris
 gtk_clipboard_wait_is_text_available

diff --git a/gtk/gtkclipboard.c b/gtk/gtkclipboard.c
index 496e44cf8604be5c8ac9415542111dcf49eb839e..72bc0dea6c2a7b58a91b126e1dfef27863a7a0cc 100644 (file)
--- a/gtk/gtkclipboard.c
+++ b/gtk/gtkclipboard.c
@@ -930,6 +930,17 @@ gtk_clipboard_set_image (GtkClipboard *clipboard,
   gtk_target_list_unref (list);
 }
 
+/**
+ * gtk_clipboard_set_surface:
+ * @clipboard: a #GtkClipboard object
+ * @surface: a cairo image surface
+ *
+ * Sets the contents of the clipboard to the given cairo image surface.
+ * GTK+ will take responsibility for responding for requests for the
+ * image, and for converting the image into the requested format.
+ * 
+ * Since: 3.94
+ **/
 void
 gtk_clipboard_set_surface (GtkClipboard    *clipboard,
                            cairo_surface_t *surface)
@@ -1651,6 +1662,24 @@ gtk_clipboard_wait_for_image (GtkClipboard *clipboard)
   return results.data;
 }
 
+/**
+ * gtk_clipboard_wait_for_surface:
+ * @clipboard: a #GtkClipboard
+ *
+ * Requests the contents of the clipboard as image and converts
+ * the result to a cairo surface. This function waits for
+ * the data to be received using the main loop, so events,
+ * timeouts, etc, may be dispatched during the wait.
+ *
+ * Returns: (nullable) (transfer full): a newly-allocated cairo surface
+ *     object which must be disposed with cairo_surface_destroy(), or
+ *     %NULL if retrieving the selection data failed. (This could
+ *     happen for various reasons, in particular if the clipboard
+ *     was empty or if the contents of the clipboard could not be
+ *     converted into an image.)
+ *
+ * Since: 2.6
+ **/
 cairo_surface_t *
 gtk_clipboard_wait_for_surface (GtkClipboard *clipboard)
 {
@@ -1676,6 +1705,7 @@ gtk_clipboard_wait_for_surface (GtkClipboard *clipboard)
 
   return results.data;
 }
+
 static void 
 clipboard_uris_received_func (GtkClipboard *clipboard,
                              gchar       **uris,